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MSX DEBUGGER 


DEBUGGER is a programmers' tool to test machine 
code programs. 


Loading Instructions 

To load the program you must put the disk in the disk 
drive and reset your computer. The program will load 
automatically. On the disk two versions of the 
DEBUGGER are supplied. You can choose between 
these versions after loading by pressing the appropriate 
key as given in the menu. The version to run under 
MSX DOS will be executed directly after loading. The 
other version is included for debugging programs under 
MSX DISK BASIC and will not be executed. After 
loading, this version will start up MSX DISK BASIC as 
usual. 


To start this debugger you must type: 

CALL DEBUG <RETURN> from within BASIC. When 
you start up the DOS version, the message "Too many 
disk drives attached" may appear. When this happens 
reset your computer while depressing the <CTRL> key. 
This will stop the two drive simulation of the computer 
so that more memory is available for the program. If 
you still see this message, remove one of your disk 
drives and start up again. 


In the explanation the following syntax is used: 
{KEY} COMMAND <DATA-l>[,DATA-2] 
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In this syntaxis specification, {KEY} is the key you 
must input to execute the COMMAND. The command 
has two inputs: DATA-1 is necessary, hence the '<’ and 
V signs, DATA-2 is optional. Example: 

{L} list [from] [,up to] 


L : Disassemble the code from the last used 

address. 

L100 : Disassemble the code from address &H100. 

LI00,200 : Disassemble the code from address &H100 

up to address &H200. 

L,200 : Disassemble the code from the last used 

address up to address &H200. 

All input of addresses and data must be in hexadecimal 
format. Output from the DEBUGGER is also given in 
hexadecimals. 

Commands to display or change memory 
contents 

{L} List [from][,upto] 

List gives a disassembly starting from the given 
address. 


{D} Dump [from] [,upto] 

Displays the contents from the memory in hexadecimal 
and ASCI format. The characters with ASCII code &H00 
up to &H1F are shown as periods while all characters 
with a code above &H7F are shown as characters &H00 
to &H7F. 
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{S} Set <address>[,data string] 

With this command you can change the contents of 
memory. The data at the specified address will be 

changed to the given data string (optional). When no 
data string is specified the address with its current 
contents is shown. Now you can either change this by 
typing a data string or skip to the next address by 
typing a <RETURN>. To exit from this input mode type 
a non-hexadecimal value and a <RETURN>. 

{F} Find [ address] [,data string] 

You can use this command to find certain values in 
memory. It will display a one line hex dump of the 
address where the wanted data string was found. 
Remember that the debugger will always find at least 
one because it checks the whole memory. So when you 
run under DOS, any occurrence above &HC000 will be 
one of the buffers in the DEBUGGER itself. When 
running under BASIC, any occurrence above &H4CK 0 
and below &H7FFF will again be from the 
DEBUGGER itself. 


{1} fill <from><,uptox,byte> 

Fills the memory between and including the specified 
addresses with the given value. 


{M} Move <fromx,uptox,to> 

Moves the block of memory to the specified address 



Commands to execute programs 

{X} Register [A, F, Be, De, HI, iX, iY, Sp, Pc] 
















To display the contents of the registers, stack pointer, 
and program counter you must enter {X}<RETURN>. The 
instruction pointed to by the program counter is 
displayed. To change any of the registers type X and 
then any of the above used capital letters. So to change 
the register BC type {XB}<RET>. The contents of the 
register will be displayed and you will be able to enter a 
new hexadacimal value or abort by pressing 
<RETURN>. The alternate register set is not displayed. 
The flags are displayed as register F and as: SZ-H-PNC. 
When a letter is capital, then the flag is set, otherwise 
the flag is reset. To set the Zero flag and reset all 
others type: {XF}<RETURN>, {40}<RETURN>. 


{T} Trace [number of instructions] 

Single step through a number of instructions can be 
performed by the trace command. The address where the 
trace starts is the address set by the program counter. 
After each step the contents of the registers and the 
next instruction are displayed. 

The trace does not work in ROM and you should not 
trace through slot calls that change page 3 or through 
interrupt handlers. The HALT instruction is not executed 
because the DEBUGGER always disables the 
interrupts. 


{K} sKipp 

Skipp is a special trace command. It always puts a 
breakpoint after the instruction to perform and then 
executes it. This instruction is very useful with calls 
you do not want to single step because they will be 
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executed completely in one go. This command is only 

useful with the CALL, RST and DJNZ instructions. Other 

instructions are executed as if it was a normal trace 

except for jumps. Do not use this command with jumps; 

the breakpoint will not be found. 

{G} Goto [address] [,breakpoint] 

Goto executes a program in the normal way. When no 

address is specified the contents of the program counter 

is used as the start address. There are two ways to 

return to the debugger: firstly, by setting a breakpoint 

where the program must stop execution Secondly, when 

no breakpoint is set, upon execution of the last 

RET-instruction in the routine, the debugger will be 

re-entered. 


Commands for disk handling 

{B} Begin of file 

Displays the begin of file pointer. By entering an other 
value you can change this or type a <RETURN> to leave 
it unchanged. Any loading or saving will be done from 
this address. 


{E} End of file 

Displays the end of file pointer. You can change this in 
the same way as the begin of file pointer. 


{R} Read [drive:]<filename> 

Reads a file from disk to the address as set by the 
begin of file pointer. After loading the end of file 
pointer will be set to the last byte loaded. Both 
pointers are displayed. 
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{W} Write [drive:]<filename> 

Writes the data from the begin of file pointer up to the 
end of file pointer to the disk. 

{C} Catalog [drive:]<filename> 

Shows the directory of the specified drive as a normal 
DIR (or FILES) command. Wildcards are allowed. 

Miscellaneous 

{Z} display siZe 

Toggles the display size between 40 and 80 columns 
(only on MSX 2). 

{O} slOt 

Toggles ROM and RAM on page 0 
(i.e. &H0000-&H3FFF). 

* 

{Q} Quit 

Returns to MSX DISK BASIC or resets the computer 
when running under MSX DOS. 

Data strings 

Some instructions accept a data s ring (see 
specifications above). Under a data string the 
DEBUGGER recognizes any string of hexadecimal 
numbers up to 16 bit and any ASCII strings. 

Example : 12,345/HELLO\D 

Gives : 12 45 03 48 45 4C 4C 4F 0D 

Editing 

The normal DOS editor is used. 


6 


Cursor up 
Cursor down 
Cursor left 
Cursor right 
Insert 
Delete 

Backspace 


: Delete line. 

Restore line. 

Character left. 

Character right. 

: Toggle insert mode. 

: Delete the character under the cursor (not 
shown). 

: Delete the character in front of the 
cursor. 


Refer to your computer manual or more editing 
commands. 


Error messages 

Error: atam8u Adocu 
number. 


tent: Untitled; status: preparing 


Overlaps program: The command you wanted to perform 
overlaps the DEBUGGER so it will not be executed. 
Begin overlaps program: The beginning of file pointer is 


set into the DEBUGGER. 


File not found: The requested file was not found on the 
specified disk. 

Complete file not read: The file will overlap the 
DEBUGGER and is therefore only loaded up to the start 
of the DEBUGGER. 

Begin > End: The beginning of file pointer is set past 
the end of file pointer. 

Cannot create: Disk file could not be created. 

Write error: Disk write error (disk full). 

Aborted: The execution was aborted by the user. 
Execution ended: While running a program the 
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DEBUGGER is entered by the last RET-instruction. 
Cannot trace in ROM: The DEBUGGER is unable to 
trace a program resident in ROM. 

Memory usage 

The DEBUGGER will be loaded at &H4000 when 
running under BASIC and uses up to &H5FFF. The 
memory contents while running under DOS will be: 


Normal: 

Debugger: 

0000 Dos calls 

0000 

Dos calls 

005B Default FCB 

005B 

Default FCB 

0080 Default DMA 

0080 

Default DM A 

???? TPA 

BFFF 

TPA 

???? Stack 

cooo 

DEBUGGER 


???? 

it#* 

Stack 


When sta ting the DOS version of the DEBUGGER the 
free stack space is shown. At least a stack of &H0100 is 
recommended. When the stack space is not sufficient 
remove one of the disk drives or start up while 
depressing the <CTRL> key. 


Printer 

To direct output to the printer type <CTRL>+<P>. All 
output to the screen will also be sent to the printer. To 
turn it off again type <CTRL>+<N>. 


MSX is a registered trade 



ark of Microsoft Corporation. 
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